Celebrities Endpoint

The Celebrities endpoint retrieves Gracenote information about entertainment personalities, identified by their Gracenote personId. This endpoint provides a default data set, and with an additional entitlement, provides Enhanced Celebrity data.

The default Celebrities endpoint provides general information, including:

  • Awards
  • Basic biographical information such as birth date and place of birth
  • Images (assets), such as celebrity headshots
  • Mediography (basic biographical information)
  • Person ID for linking to cast and crew in Programs API
  • Primary and alternate names
  • The Enhanced Celebrity entitlement extends this data significantly. See the Data Dictionaries.

This entitlement extends the default Celebrities data to include:

  • Nationality
  • Ethnicity
  • Participant Types
  • Biographies
  • Relationships
  • Relationship Events
  • Education
  • Milestones
  • Notes
  • Quotes
  • Enhanced Awards
  • Highlights
  • Social Media
  • Enhanced Images (baselineAssets)

Updating Celebrities Data

All celebrities are marked with a unique updateId, denoting current information for the celebrity. Changes to any person data will result in assignment of a new updateId, which allows you to pull deltas since last retrieval of celebrity information. You can use celebrity information in conjunction with program cast, crew, and awards information to provide a searchable and connected mediography for celebrities.

Celebrity Requests

The Celebrities endpoint provides information about entertainment personalities, identified by personId attribute.

For an additional subscription, you can enable Enhanced Celebrity for additional information about celebrities including additional images, award information, and others. See Enhanced Celebrity Requests.

Celebrities

Celebrities is a collection of personal facts for the most popular performers and key production crew members appearing in linear and on demand services. Metadata includes a recent red carpet or publicity photo, a.k.a. and translated names, major industry awards nominations and wins, and a comprehensive mediography of credited roles in television and movie productions. Gracenote IDs are applied to all person, name, award, and credited program references to provide connectivity within the On metadata suite.

A screenshot of a movie Description automatically generated

Celebrities Data Structure and Relationships

Celebrities Schema

Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.

To explore the relationships among all endpoints, see the interactive schema documentation.

XML Schema URL

http://files.api.gracenote.com/xsd/on_update_celebrities_3.22.xsd

Celebrities Key Fields

The following data dictionary shows the XPATH of key elements and attributes for “core” celebrity content.

The XPATH in the table below is relative to: on/celebrities/person

XPATH Element\Attribute Description Example
@personId Gracenote unique identifier for the celebrity 62982
type Celebrity type: person, group, animal Person
profile\gender\ The celebrity's gender, optional Male
profile\birthName\ The celebrity's full name at birth, optional Thomas Jeffrey Hanks
profile\birthPlace\ The celebrity's birthplace, optional Concord, California, USA
profile\birthDate\ The celebrity's birth date, optional 1956-07-09
mediography\ Productions on which this celebrity worked in some credited role. 26553, “Cast Away”, 2000, Actor, Producer
awards\ The celebrity's nominated and received awards. 2001 “Academy Award”, “Actor in a Leading Role”, Winner
assets\ Image associated with the celebrity. assets/62982_v9_bc.jpg

Celebrity Names

The XPATH in the table below is relative to: on/celebrities/person/localizedPersonNames/localizedPersonName

XPATH Element\Attribute Description Example
@nameId Gracenote unique identifier for the celebrity name associated with the credited role. 171296
@primary Flag indicating the primary name true
localizedName/@language Name language en
localizedName/@sort Flag indicating the sort name true
localizedName/first/ First name Roseanne
localizedName/last/ Last name Barr

Celebrity names reflect name changes as well as different names in celebrity mediagraphy credits. The primary name flag is available.

personId nameId primary lang sort Name - first Name - last
56714 56714   en   Roseanne  
56714 56714   ja true ロザンヌ  
56714 153382   en   Roseanne Arnold
56714 153382   ja   ロザンヌ・アーノルド  
56714 153382   ja true ロザンヌアーノルド  
56714 171296 true en   Roseanne Barr
56714 171296 true ja   ロザンヌ・バー  
56714 171296 true ja true ロザンヌバー  
56714 506184   en   Roseanne Thomas

Enhanced Celebrity Key Fields

“Enhanced Celebrity” metadata can be licensed and optionally added to the Celebrities endpoint. This metadata comes from the Gracenote “Studio Data” product and provides additional information and images that compliments the “core” celebrity metadata.

The following data dictionary shows the key elements and attributes for “enhanced” celebrity content. This content is distinct from the “core” content.

The XPATH in the tables below is relative to: on/celebrities/person

XPATH Element\Attribute Description Example
profile\deathPlace The celebrity's place of death. New York, New York USA
profile\deathCause The celebrity's official cause of death. Cardiac arrest
nationality The celebrity's nationality United States
ethnicity The celebrity's ethnicity American
participantTypes Career role type. e.g. "Director" Actor, Producer, Director, Writer
biographies The factual, all-encompassing portrait of a subject’s life and career, written in chronological order. “With an on-screen persona so likable that he was often referred to as "America's Dad," Tom Hanks cemented…”
relationships All family and partner relationships. Companion, Wife, Rital Wilson
relationshipEvents Significant relationship events, such as marriage and divorce and their respective dates. Rita Wilson, “Began dating September, 1985.”
educations Education information of the celebrity. California State University, Sacramento, Theater
milestones Career milestones of the celebrity. 2023, “Co-starred in the comedy "Asteroid City"”
notes Notes are interesting trivia items that give personal insight about their backgrounds and interests. Not all artists will have bio notes. “Hanks collected manual typewriters, using them to write scripts and correspondence.”
quotes Insightful and/or humorous celebrity citations culled from published interviews. Not all artists will have quotes. "Being a media darling is a fate I do not wish on my worst enemy…”
enhancedAwards Enhanced awards, to differentiate from “core” data awards 2022, Critics Choice Super Awards, Best Actor in a Science Fiction/Fantasy Movie, Nominee
highlights A curated list of up to 10 interesting facts from the celebrity's personal and professional profile. “Hanks, 68, was born on July 9, 1956 in Concord, CA with the name Thomas Jeffrey Hanks.”
socialMedia The celebrity's official social media page links or ids. Twitter, @tomhanks
baselineAssets Enhanced Celebrity assets (images), to differentiate from “core” data images. http://media.baselineresearch.com/images/2134666/2134666_full.jpg

Celebrity Images

The XPATH in the tables below is relative to: on/celebrities/person/assets/asset

XPATH Element/Attribute Description Example
@assetId Gracenote image identifier s28719_lw_h15_ac
@type MIME content type image/png
@lastModified Timestamp of last asset/metadata modification 2019-09-21T19:20:11Z
@width Maximum image width 3840
@height Maximum image height 2160
@category Image category Source Logo - dark
@ratio Image aspect ratio 16:9
URI/ Relative Image URI assets/s28719_lw_h15_ac.png

The image asset structure and general handling logic is common to images of all entities, however, categories and aspect ratios vary depending on the entity. The following table provides the core celebrity logo categories and aspect ratios.

Category Description Ratios
Photo - Headshot Standard celebrity image 3:4

For more information, see the supplementary document On API Image Category & Tier Definitions (auto-download). 

Enhanced Celebrity Imagery

The enhanced image assets are additive to the “core” image asset. The XPATH in the tables below is relative to: on/celebrities/person/baselineAssets/baselineAsset

XPATH Element/Attribute Description Example
@assetId Gracenote image identifier 1807001_full
@type MIME content type image/png
@sizeType Image size type full
@width Image width 3840
@height Image height 2160
@category Image category Head Shot
caption/ Image caption Roseanne Barr at arrivals for An Evening with the Cast of ...
url/ Full image URL http://media.baselineresearch.com/images/1807001/1807001_full.jpg

Enhanced Celebrity images come in several categories and varying aspect ratios but include the image dimensions (width x height). For more information on Enhanced Celebrity imagery.

Entity Relationship Diagram

The following ERD illustrates the ID relationships from a celebrity record to other relevant endpoint objects within On API.

  • The personIds and nameIds are referenced from the Program cast/crew credits.
  • The mediography element has a program rootId which references a Program record with any TMSId title / description language.

A close-up of a card Description automatically generated

API and Example Responses

API 

http://on-api.gracenote.com/v3/Celebrities
?updateId=[updateId value]
&limit=[limit value]
&api_key=[your-api-key]

Request Parameters

Parameter Required? Description
api_key Yes Your API key
updateId No Update token. Returns celebrities beginning with specified updateId, which is sequential numeric offset received in response.
limit No Batch size. Maximum number of celebrities to be returned by API. Use with updateId.
personId No For non-batch lookups. Comma-separated list of personIds for celebrity data.

Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.

Example Requests

Return full list of celebrities in batches of 1000:

http://on-api.gracenote.com/v3/Celebrities?updateId=0&limit=1000&api_key=<your-api-key>

Return a specific celebrity:

 http://on-api.gracenote.com/v3/Celebrities?personId=100&api_key=<your-api-key>

The links is a response of default Celebrities data for The Rock:

http://on-api.gracenote.com/v3/Celebrities?personId=235135&api_key=<your-api-key>

Example Responses

Celebrities XML examples

The Rock Celebrities Response

Enhanced Celebrity Requests

Enhanced Celebrity is an additional entitlement to extend the Celebrities endpoint , including:

  • Nationality
  • Ethnicity
  • Participant Types
  • Biographies
  • Relationships
  • Relationship Events
  • Education
  • Milestones
  • Notes
  • Quotes
  • Enhanced Awards
  • Highlights
  • Social Media
  • Enhanced Images (baselineAssets)

The Celebrities endpoint provides a default data set, and with an additional entitlement, provides enhanced celebrity data. See Data Dictionaries and Controlled Vocabularies.

Enhanced Celebrity Example Responses

The links below are is a response of Enhanced Celebrity entitlement for The Rock:

http://on-api.gracenote.com/v3/Celebrities?personId=235135&api_key=<your-api-key>

Response: "The Rock" Enhanced Celebrity Response